v3.17.2

Compare Source

3.17.2 is a regularly-scheduled patch release.

✅ Upgrading

Our recommendation for upgrading is to run:

npx nuxi@latest upgrade --dedupe

This will deduplicate your lockfile as well, and help ensure that you pull in updates from other dependencies that Nuxt relies on, particularly in the unjs ecosystem.

👉 Changelog

compare changes

🔥 Performance

• nuxt: Tree-shake router's handleHotUpdate in production (#​31971)

🩹 Fixes

• nuxt: Ensure asyncData is initialised before effects run (#​31946)
• nuxt: Skip view transition if user agent provides one before defining transition (#​31945)
• nuxt: Improve hashing for complex body in useFetch (#​31963)
• nuxt: Immediately call asyncData within client-only components (#​31964)
• nuxt: Don't render errors if event is already handled (#​31966)
• nuxt: Track whether need to reinit asyncData separately from deps (#​31965)
• nuxt: Preserve params/meta/matched with universal router (#​31950)
• nuxt: Respect scroll behavior set by scrollToTop (#​31914)
• nuxt: Load live data from vfs even if a file exists in buildDir (#​31969)
• nuxt: Short circuit middleware when validate returns false (#​31967)
• nuxt: Ensure useAsyncData reactive to key changes when immediate: false (#​31987)
• nuxt: Resolve real paths imported into virtual files (0bb07f129)
• webpack: Broaden WarningFilter type (2a79dbd68)
• schema: Broaden warningIgnoreFilters (a62e808ac)

📖 Documentation

• Add missing article (#​31952)
• Improve @nuxt/kit documentation (#​31793)
• Fix type issues in twoslash blocks (85ab105b8)
• Add events page (#​31977)

🏡 Chore

• Update approved builds (02b33cc58)
• Sort package keys (06aabc548)

✅ Tests

• Update bundle size snapshot (e03d44b47)
• Update bundle size (7f75f5ea5)
• Update bundle size again (e8a244bfc)
• Use asyncDataDefaults.value (91568c5da)

🤖 CI

• Run docs workflow against pull requests (08f968903)
• Run tests against node v20 (3c97d3493)

❤️ Contributors

• Daniel Roe (@​danielroe)
• Alex Liu (@​Mini-ghost)
• Martins Zeltins (@​martinszeltins)
• Ivan Martianov (@​ivansky)
• Lorenzo Fiamingo (@​lorenzofiamingo)
• James (@​Koshux)

v3.17.1

Compare Source

3.17.1 is the next patch release.

✅ Upgrading

Our recommendation for upgrading is to run:

npx nuxi@latest upgrade --dedupe

This will deduplicate your lockfile as well, and help ensure that you pull in updates from other dependencies that Nuxt relies on, particularly in the unjs ecosystem.

👉 Changelog

compare changes

🩹 Fixes

• nuxt: Check if match exists with new unplugin filter (#​31929)
• nuxt: Reinitialise stale async data (#​31940)
• nuxt: Skip view transition if user agent is providing one (#​31938)
• nuxt: Trigger execute when non-immediate fetch key changes (#​31941)
• nuxt: Don't redirect when route has trailing slash (#​31902)
• ui-templates: Use escapeHTML from vue (8e4b8d62f)
• schema: Add @vue/shared dependency (7d445c963)

📦 Build

• Copy README/LICENSE from repo root (8e287d556)

🏡 Chore

• Update docs version (db5ad4a8f)
• Add docs directory to publish scripts (d3bcad632)

✅ Tests

• Update snapshots (a197d1087)

❤️ Contributors

• Daniel Roe (@​danielroe)
• Pooya Parsa (@​pi0)
• Kyohei Sonokawa (@​kyohei-23)
• Lorenzo Fiamingo (@​lorenzofiamingo)

v3.17.0

Compare Source

👀 Highlights

This release brings a major reworking of the async data layer, a new built-in component, better warnings, and performance improvements!

📊 Data Fetching Improvements

A major reorganization of Nuxt's data fetching layer brings significant improvements to useAsyncData and useFetch.

Although we have aimed to maintain backward compatibility and put breaking changes behind the experimental.granularCachedData flag (disabled by default), we recommend testing your application thoroughly after upgrading. You can also disable experimental.purgeCachedData to revert to the previous behavior if you are relying on cached data being available indefinitely after components using useAsyncData are unmounted.

👉 Read the the original PR for full details (#​31373), but here are a few highlights.

Consistent Data Across Components

All calls to useAsyncData or useFetch with the same key now share the underlying refs, ensuring consistency across your application:

<!-- ComponentA.vue -->
<script setup>
const { data: users, pending } = useAsyncData('users', fetchUsers)
</script>

<!-- ComponentB.vue -->
<script setup>
// This will reference the same data state as ComponentA
const { data: users, status } = useAsyncData('users', fetchUsers)
// When either component refreshes the data, both will update consistently
</script>

This solves various issues where components could have inconsistent data states.

Reactive Keys

You can now use computed refs, plain refs, or getter functions as keys:

const userId = ref('123')
const { data: user } = useAsyncData(
  computed(() => `user-${userId.value}`),
  () => fetchUser(userId.value)
)

// Changing the userId will automatically trigger a new data fetch
// and clean up the old data if no other components are using it
userId.value = '456'

Optimized Data Refetching

Multiple components watching the same data source will now trigger only a single data fetch when dependencies change:

// In multiple components:
const { data } = useAsyncData(
  'users', 
  () => $fetch(`/api/users?page=${route.query.page}`),
  { watch: [() => route.query.page] }
)

// When route.query.page changes, only one fetch operation will occur
// All components using this key will update simultaneously

🎭 Built-In Nuxt Components

<NuxtTime> - A new component for safe time display

We've added a new <NuxtTime> component for SSR-safe time display, which resolves hydration mismatches when working with dates (#​31876):

<template>
  <NuxtTime :datetime="Date.now()" />
</template>

The component accepts multiple time formats and gracefully handles both client and server rendering.

Enhanced <NuxtErrorBoundary>

The <NuxtErrorBoundary> component has been converted to a Single File Component and now exposes error and clearError from the component - as well as in the error slot types, giving you greater ability to handle errors in your templates and via useTemplateRef (#​31847):

<NuxtErrorBoundary @&#8203;error="handleError">
  <template #error="{ error, clearError }">
    <div>
      <p>{{ error.message }}</p>
      <button @&#8203;click="clearError">Try again</button>
    </div>
  </template>
  
  <!-- Content that might error -->
  <MyComponent />
</NuxtErrorBoundary>

🔗 Router Improvements

<NuxtLink> now accepts a trailingSlash prop, giving you more control over URL formatting (#​31820):

<NuxtLink to="/about" trailing-slash>About</NuxtLink>
<!-- Will render <a href="/about/"> -->

🔄 Loading Indicator Customization

You can now customize the loading indicator with new props directly on the component (#​31532):

• hideDelay: Controls how long to wait before hiding the loading bar
• resetDelay: Controls how long to wait before resetting loading indicator state

<template>
  <NuxtLoadingIndicator :hide-delay="500" :reset-delay="300" />
</template>

📚 Documentation as a Package

The Nuxt documentation is now available as an npm package! You can install @nuxt/docs to access the raw markdown and YAML content used to build the documentation website (#​31353).

💻 Developer Experience Improvements

We've added several warnings to help catch common mistakes:

• Warning when server components don't have a root element #​31365
• Warning when using the reserved runtimeConfig.app namespace #​31774
• Warning when core auto-import presets are overridden #​29971
• Error when definePageMeta is used more than once in a file #​31634

🔌 Enhanced Module Development

Module authors will be happy to know:

• A new experimental.enforceModuleCompatibility allows Nuxt to throw an error when a module is loaded that isn't compatible with it (#​31657). It will be enabled by default in Nuxt v4.
• You can now automatically register every component exported via named exports from a file with addComponentExports #​27155

🔥 Performance Improvements

Several performance improvements have been made:

• Switched to tinyglobby for faster file globbing #​31668
• Excluded .data directory from type-checking for faster builds #​31738
• Improved tree-shaking by hoisting the purgeCachedData check #​31785

✅ Upgrading

Our recommendation for upgrading is to run:

npx nuxi@latest upgrade --dedupe

This refreshes your lockfile and pulls in all the latest dependencies that Nuxt relies on, especially from the unjs ecosystem.

👉 Changelog

compare changes

🚀 Enhancements

• nuxt: Accept hideDelay and resetDelay props for loading indicator (#​31532)
• nuxt: Warn server components need root element (#​31365)
• docs: Publish raw markdown/yaml docs as @nuxt/docs (#​31353)
• kit,nuxt: Pass dotenv values from loadNuxtConfig to nitro (#​31680)
• nuxt,vite: Support disabling scripts in dev mode (#​31724)
• nuxt: Warn if user uses reserved runtimeConfig.app namespace (#​31774)
• kit,schema: Allow throwing error if modules aren't compatible (#​31657)
• nuxt: Extract middleware when scanning page metadata (#​30708)
• nuxt: Warn if core auto-import presets are overridden (#​29971)
• nuxt: Scan named exports with addComponentExports (#​27155)
• nuxt: Convert <NuxtErrorBoundary> to SFC + expose error/clearError (#​31847)
• nuxt: Add <NuxtTime> component for ssr-safe time display (#​31876)
• nuxt: Add trailingSlash prop to <NuxtLink> (#​31820)

🔥 Performance

• kit,rspack,webpack: Switch to tinyglobby (#​31668)
• kit: Exclude .data directory from type-checking (#​31738)
• nuxt: Hoist purgeCachedData check to improve tree-shaking (#​31785)
• nuxt: Remove oxc-parser manual wasm fallback logic (#​31484)
• nuxt: Remove unecessary type check for useFetch (#​31910)

🩹 Fixes

• kit,vite: Ensure all modulesDir paths are added to fs.allow (#​31540)
• nuxt: Pass slots through to lazy hydrated components (#​31649)
• vite: Do not return 404 for dev server handlers which shadow /_nuxt/ (#​31646)
• nuxt: Sync error types for useLazyAsyncData (#​31676)
• nuxt: Strip base url from error.url (#​31679)
• nuxt: Render inline styles before app:rendered is called (#​31686)
• nuxt: Update nitro imports (0bec0bd26)
• nuxt: Check for fallback attribute when stripping <DevOnly> (c1d735c27)
• vite: Invalidate files not present in module graph (ecae2cd54)
• nuxt: Do not add manifest preload when noScripts (c9572e953)
• nuxt: Do not prompt to update compatibilityDate (#​31725)
• nuxt: Show brotli size by default when analyzing bundle (#​31784)
• nuxt: Always pass statusMessage when rendering html error (#​31761)
• nuxt: Error when definePageMeta is used more than once (#​31634)
• nuxt: Parse error.data before rendering error.vue (#​31571)
• nuxt: Use single synced asyncdata instance per key (#​31373)
• nuxt: Use useAsyncData in console log (#​31801)
• nuxt: Wait for suspense to resolve before handling NuxtErrorBoundary error (#​31791)
• vite: Disable preserveModules (#​31839)
• nuxt: Align pending with status value for v4 (#​25864)
• nuxt: Consider full path when de-duplicating routes (#​31849)
• nuxt: Augment nuxt/app in generated middleware and layouts declarations (#​31808)
• nuxt: Correct order of args passed to withoutBase (f956407bb)
• vite: Dedupe vue in vite-node dev server (f3882e004)
• ui-templates: Pass pointer events through spotlight div in error dev template (#​31887)
• kit: Include user-defined types before internal ones in tsconfig.json (#​31882)
• nuxt: Do not purge nuxt data if active useNuxtData (#​31893)
• nuxt: Do not include components of key in useFetch watch sources (#​31903)
• nuxt: Use first existing modulesDir to store build cache files (#​31907)

💅 Refactors

• nuxt: Use shallowRef for primitives as well (#​31662)
• nuxt: Move island renderer into its own event handler (#​31386)
• nuxt: Remove unneeded import (#​31750)
• nuxt: Use _replaceAppConfig when applying hmr (#​31786)
• nuxt: Use new unplugin filter options (#​31868)
• schema: Do not generate types for ConfigSchema (#​31894)

📖 Documentation

• Add note on extending auto-imports (#​31640)
• Improve description of app.vue (#​31645)
• Use video-accordion video and add more videos (#​31655)
• Add description of templateParams to seo docs (#​31583)
• Refine auto-imports documentation (#​31700)
• Fix nuxt logo on website badge (#​31704)
• Update tailwindcss link (b5741cb5a)
• Adjust description of useHydration (#​31712)
• Remove trailing slash (#​31751)
• Remove comment about callOnce returning value (#​31747)
• Use vs. consistently (#​31760)
• Update nitro addServerHandler example (#​31769)
• Add supporting shared folder video (#​31651)
• Update example for component auto-import in nuxt modules (#​31757)
• Refine nuxt kit components documentation (#​31714)
• Use trailing slash for vitest link (82de8bcf8)
• Fix casing (#​31805)
• Add discord and nuxters links (#​31888)
• Fix typos (#​31898)

📦 Build

• nuxt: Use vue-sfc-transformer to process sfcs (#​31691)

🏡 Chore

• Update renovate config (565c0b98e)
• Upgrade webpack separately (e1f5db34f)
• Update internal ui-templates licence to MIT (f8059fb8b)
• Sort package.json (a6cbd71f8)

✅ Tests

• nuxt: Add customizable test api for pages tests (#​31619)
• kit: Fix tests when running on Windows (#​31694)
• Update page metadata snapshot (89a596075)
• Add basic runtime tests for <NuxtErrorBoundary> (4df92c45f)
• Add version to mock nuxt (915fae2fd)
• Update assertion for pendingWhenIdle (08f2224c8)
• Remove incorrect assertions (fdc4b5343)
• Update tests for purgeCachedData (c6411eb17)

🤖 CI

• Add notify-nuxt-website workflow (#​31726)

❤️ Contributors

• @​beer (@​iiio2)
• Julien Huang (@​huang-julien)
• Daniel Roe (@​danielroe)
• Saeid Zareie (@​Saeid-Za)
• Bobbie Goede (@​BobbieGoede)
• Damian Głowala (@​DamianGlowala)
• Maxime Pauvert (@​maximepvrt)
• Leonid (@​john-psina)
• Wind (@​productdevbook)
• Arkadiusz Sygulski (@​Aareksio)
• Rohan Dhimal (@​drowhannn)
• xjccc (@​xjccc)
• Robin (@​OrbisK)
• Alex Liu (@​Mini-ghost)
• Daniel Kelly (@​danielkellyio)
• Jeffrey van den Hondel (@​jeffreyvdhondel)
• Alexander Lichter (@​TheAlexLichter)
• Sébastien Chopin (@​atinux)
• Yizack Rangel (@​Yizack)
• Joaquín Sánchez (@​userquin)
• IlyaL (@​ilyaliao)
• Ben McCann (@​benmccann)
• Anthony Fu (@​antfu)
• Alexandru Ungureanu (@​unguul)

v3.16.2

Compare Source

3.16.2 is the next patch release.

✅ Upgrading

Our recommendation for upgrading is to run:

npx nuxi@latest upgrade --dedupe

This will deduplicate your lockfile as well, and help ensure that you pull in updates from other dependencies that Nuxt relies on, particularly in the unjs ecosystem.

👉 Changelog

compare changes

🔥 Performance

• nuxt: Improve tree-shaking of useRequestEvent on client (#​31586)

🩹 Fixes

• nuxt: Pass down attrs to <Body> and <Html> (#​31513)
• nuxt: Use greedy catchall when /index is the last segment (#​31528)
• nuxt: Reset page:loading:end hook before navigation (#​31504)
• nuxt: Write initial cookie value if different from document.cookie (#​31517)
• nuxt: Support template string quotes in resolveComponent (#​31526)
• nuxt: Show fatal errors thrown in middleware (#​31518)
• nuxt: Use name to index route providers in dev (#​31544)
• nuxt: Improve default scroll behaviour (#​31545)
• vite: Return 404 for non-existent _nuxt/ paths in development (#​31543)
• nuxt: Pass error data to error.vue (#​31573)
• nuxt: Use unhead v2 api in default welcome + error pages (#​31584)
• nuxt: Improve consistency of page metadata extraction (#​31306)
• nuxt: Do not remove meta when scanPageMeta is disabled (0ba454b21)

💅 Refactors

• nuxt: Simplify conditional branches of <NuxtPage> (#​31561)
• Replace useServerHead in onPrehydrate with useHead (#​31585)

📖 Documentation

• Move custom directories note to the correct place (#​29100)
• Update example to useTemplateRef (#​31458)
• Provide async function for $fetch (#​31459)
• Mention the possibility to scan pages based on a pattern (#​31462)
• Add dedupe flag (#​31467)
• Improve refreshNuxtData docs (#​31448)
• Add missing -- before --template (#​31469)
• Migrate to @​nuxt/content v3 (#​31150)
• Fix icon for main docs (e7828d9c6)
• Save selected package manager (#​31520)
• Improve refresh nuxt data example (#​31487)
• Note that middleware runs on error pages as well (df14c0263)
• Replace all 'Nuxt 3' with 'Nuxt' in documentation (#​31519)
• resolveComponent only auto-imports components with literal strings (#​31511)
• Add ticks around tsconfig.json (#​31473)
• Capitalize heading (#​31523)
• Update links to unhead.unjs.io (1913febbb)
• Document that props are passed via server components via query (db7688219)
• Improve description of page:start and page:finish hooks (#​31570)

🏡 Chore

• Ignore builds (e34ae380d)

✅ Tests

• Avoid invalid nested font face (#​31524)
• Add test for loading indicator with custom key (25ca9b819)
• Add test for custom prop + loading indicator (94bfed031)
• Update snapshot (55134fc2a)

❤️ Contributors

• Daniel Roe (@​danielroe)
• Julien Huang (@​huang-julien)
• Bobbie Goede (@​BobbieGoede)
• Alex Liu (@​Mini-ghost)
• Dennis Adriaansen (@​dennisadriaans)
• Guillaume Chau (@​Akryum)
• @​beer (@​iiio2)
• 翠 / green (@​sapphi-red)
• xjccc (@​xjccc)
• Hugo Richard (@​HugoRCD)
• Sébastien Chopin (@​atinux)
• Johannes Buchholz (@​jhony1104)
• Alexander Lichter (@​TheAlexLichter)
• Matej Černý (@​cernymatej)
• Claudiu (@​sofuxro)

v3.16.1

Compare Source

compare changes

🔥 Performance

• nuxt: Use browser cache for payloads (#​31379)

🩹 Fixes

• nuxt: Restore nuxt aliases to nitro compilerOptions.paths (#​31278)
• nuxt: Use new mocked-exports (#​31295)
• nuxt: Check resolved options for polyfills (#​31307)
• nuxt: Render style component html (#​31337)
• nuxt: Add missing lazy hydration prop in regex (#​31359)
• nuxt: Fully resolve nuxt dependencies (#​31436)
• vite: Don't show interim vite build output files (#​31439)
• nuxt: Ignore prerendering unprefixed public assets (151912ec3)
• nuxt: Use more performant router catchall pattern (#​31450)
• nuxt: Prevent param duplication in typedPages implementation (#​31331)
• nuxt: Sort route paths before creating route tree (#​31454)

📖 Documentation

• Update link to vercel edge network (ec20802a5)
• Improve HMR performance note for Windows users (#​31301)
• Correct WSL note phrasing (#​31322)
• Fix typo (#​31341)
• Adjust app.head example (#​31350)
• Include package manager options in update script (#​31346)
• Add missing comma (#​31362)
• Add mention of addServerTemplate to modules guide (#​31369)
• Add rspack and remove test-utils for monorepo guide (#​31371)
• Adjust example (#​31372)
• Update experimental docs (#​31388)
• Use ini syntax block highlighting for .env files (f79fabe46)
• Improve useHydration docs (#​31427)
• Update broken docs links (#​31430)
• Mention possibility of prerendering api routes (#​31234)

🏡 Chore

• Fix gitignore (6fe9dff7e)
• Bump axios dependency in lockfile (c3352e80b)
• Lint repo (2ab20bfdc)
• Add scorecard badge (#​31302)
• Dedupe (be5d85f2b)

✅ Tests

• Migrate runtime compiler test to playwright (+ add test cases) (#​31405)
• Migrate spa preloader tests to playwright (#​31273)
• Use srvx and random port for remote provider (#​31432)

🤖 CI

• Automate release on merge of of v3/v4 (6ae5b5fdb)
• Fix workflow quoting (fef39cf3c)

❤️ Contributors

• Daniel Roe (@​danielroe)
• Anoesj Sadraee (@​Anoesj)
• Peter Radko (@​Gwynerva)
• Adam DeHaven (@​adamdehaven)
• Alex Liu (@​Mini-ghost)
• Julien Huang (@​huang-julien)
• Francesco Agnoletto (@​Kornil)
• Guillaume Chau (@​Akryum)
• imreegall (@​imreegall)
• xjccc (@​xjccc)
• Sam Blowes (@​blowsie)
• Nimit012 (@​Nimit012)
• Camille Coutens (@​Kamsou)

v3.16.0

Compare Source

👀 Highlights

There's a lot in this one!

⚡️ A New New Nuxt

Say hello to create-nuxt, a new tool for starting Nuxt projects (big thanks to @​devgar for donating the package name)!

It's a streamlined version of nuxi init - just a sixth of the size and bundled as a single file with all dependencies inlined, to get you going as fast as possible.

Starting a new project is as simple as:

npm create nuxt

Special thanks to @​cmang for the beautiful ASCII-art. ❤️

Want to learn more about where we're headed with the Nuxt CLI? Check out our roadmap here, including our plans for an interactive modules selector.

🚀 Unhead v2

We've upgraded to unhead v2, the engine behind Nuxt's <head> management. This major version removes deprecations and improves how context works:

• For Nuxt 3 users, we're shipping a legacy compatibility build so nothing breaks
• The context implementation is now more direct via Nuxt itself

// Nuxt now re-exports composables while properly resolving the context
export function useHead(input, options = {}) {
  const unhead = injectHead(options.nuxt)
  return head(input, { head: unhead, ...options })
}

If you're using Unhead directly in your app, keep in mind:

1. Import from Nuxt's auto-imports or #app/composables/head instead of @unhead/vue
2. Importing directly from @unhead/vue might lose async context

Don't worry though - we've maintained backward compatibility in Nuxt 3, so most users won't need to change anything!

If you've opted into compatibilityVersion: 4, check out our upgrade guide for additional changes.

🔧 Devtools v2 Upgrade

Nuxt Devtools has leveled up to v2 (#​30889)!

You'll love the new features like custom editor selection, Discovery.js for inspecting resolved configs (perfect for debugging), the return of the schema generator, and slimmer dependencies.

One of our favorite improvements is the ability to track how modules modify your Nuxt configuration - giving you X-ray vision into what's happening under the hood.

👉 Discover all the details in the Nuxt DevTools release notes.

⚡️ Performance Improvements

We're continuing to make Nuxt faster, and there are a number of improvements in v3.16:

1. Using exsolve for module resolution (#​31124) along with the rest of the unjs ecosystem (nitro, c12, pkg-types, and more) - which dramatically speeds up module resolution
2. Smarter module resolution paths (#​31037) - prioritizes direct imports for better efficiency
3. Eliminated duplicated Nitro alias resolution (#​31088) - leaner file handling
4. Streamlined loadNuxt by skipping unnecessary resolution steps (#​31176) - faster startups
5. Adopt oxc-parser for parsing in Nuxt plugins (#​30066)

All these speed boosts happen automatically - no configuration needed!

Shout out to CodSpeed with Vitest benchmarking to measure these improvements in CI - it has been really helpful.

To add some anecdotal evidence, my personal site at roe.dev loads 32% faster with v3.16, and nuxt.com is 28% faster. I hope you see similar results! ⚡️

🕰️ Delayed Hydration Support

We're very pleased to bring you native delayed/lazy hydration support (#​26468)! This lets you control exactly when components hydrate, which can improve initial load performance and time-to-interactive. We're leveraging Vue's built-in hydration strategies - check them out in the Vue docs.

<template>
  <!-- Hydrate when component becomes visible in viewport -->
  <LazyExpensiveComponent hydrate-on-visible />
  
  <!-- Hydrate when browser is idle -->
  <LazyHeavyComponent hydrate-on-idle />
  
  <!-- Hydrate on interaction (mouseover in this case) -->
  <LazyDropdown hydrate-on-interaction="mouseover" />
  
  <!-- Hydrate when media query matches -->
  <LazyMobileMenu hydrate-on-media-query="(max-width: 768px)" />
  
  <!-- Hydrate after a specific delay in milliseconds -->
  <LazyFooter :hydrate-after="2000" />
</template>

You can also listen for when hydration happens with the @hydrated event:

<LazyComponent hydrate-on-visible @&#8203;hydrated="onComponentHydrated" />

Learn more about lazy hydration in our components documentation.

🧩 Advanced Pages Configuration

You can now fine-tune which files Nuxt scans for pages (#​31090), giving you more control over your project structure:

export default defineNuxtConfig({
  pages: {
    // Filter specific files or directories
    pattern: ['**/*.vue'],
  }
})

🔍 Enhanced Debugging

We've made debugging with the debug option more flexible! Now you can enable just the debug logs you need (#​30578):

export default defineNuxtConfig({
  debug: {
    // Enable specific debugging features
    templates: true,
    modules: true,
    watchers: true,
    hooks: {
      client: true,
      server: true,
    },
    nitro: true,
    router: true,
    hydration: true,
  }
})

Or keep it simple with debug: true to enable all these debugging features.

🎨 Decorators Support

For the decorator fans out there (whoever you are!), we've added experimental support (#​27672). As with all experimental features, feedback is much appreciated.

export default defineNuxtConfig({
  experimental: {
    decorators: true
  }
})

function something (_method: () => unknown) {
  return () => 'decorated'
}

class SomeClass {
  @​something
  public someMethod () {
    return 'initial'
  }
}

const value = new SomeClass().someMethod()
// returns 'decorated'

📛 Named Layer Aliases

It's been much requested, and it's here! Auto-scanned local layers (from your ~~/layers directory) now automatically create aliases. You can access your ~~/layers/test layer via #layers/test (#​30948) - no configuration needed.

If you want named aliases for other layers, you can add a name to your layer configuration:

export default defineNuxtConfig({
  $meta: {
    name: 'example-layer',
  },
})

This creates the alias #layers/example-layer pointing to your layer - making imports cleaner and more intuitive.

🧪 Error Handling Improvements

We've greatly improved error messages and source tracking (#​31144):

1. Better warnings for undefined useAsyncData calls with precise file location information
2. Error pages now appear correctly on island page errors (#​31081)

Plus, we're now using Nitro's beautiful error handling (powered by youch) to provide more helpful error messages in the terminal, complete with stacktrace support.

Nitro now also automatically applies source maps without requiring extra Node options, and we set appropriate security headers when rendering error pages.

📦 Module Development Improvements

For module authors, we've added the ability to augment Nitro types with addTypeTemplate (#​31079):

// Inside your Nuxt module
export default defineNuxtModule({
  setup(options, nuxt) {
    addTypeTemplate({
      filename: 'types/my-module.d.ts',
      getContents: () => `
        declare module 'nitropack' {
          interface NitroRouteConfig {
            myCustomOption?: boolean
          }
        }
      `
    }, { nitro: true })
  }
})

⚙️ Nitro v2.11 Upgrade

We've upgraded to Nitro v2.11. There are so many improvements - more than I can cover in these brief release notes.

👉 Check out all the details in the Nitro v2.11.0 release notes.

📦 New unjs Major Versions

This release includes several major version upgrades from the unjs ecosystem, focused on performance and smaller bundle sizes through ESM-only distributions:

• unenv upgraded to v2 (full rewrite)
• db0 upgraded to v0.3 (ESM-only, native node:sql, improvements)
• ohash upgraded to v2 (ESM-only, native node:crypto support, much faster)
• untyped upgraded to v2 (ESM-only, smaller install size)
• unimport upgraded to v4 (improvements)
• c12 upgraded to v3 (ESM-only)
• pathe upgraded to v2 (ESM-only)
• cookie-es upgraded to v2 (ESM-only)
• esbuild upgraded to v0.25
• chokidar upgraded to v4

✅ Upgrading

As usual, our recommendation for upgrading is to run:

npx nuxi@latest upgrade --dedupe

This refreshes your lockfile and pulls in all the latest dependencies that Nuxt relies on, especially from the unjs ecosystem.

👉 Changelog

compare changes

🚀 Enhancements

• nuxt: Upgrade @nuxt/devtools to v2 (#​30889)
• nuxt: Granular debug options (#​30578)
• nuxt: Add type hints for NuxtPage (#​30704)
• nuxt: Support tracking changes to nuxt options by modules (#​30555)
• nuxt: Allow disabling auto-imported polyfills (#​30332)
• schema: Add runtime + internal type validation (#​30844)
• kit,nuxt,schema: Support experimental decorators syntax (#​27672)
• kit,nuxt: Allow multiple nuxts to run in one process (#​30510)
• kit: Add named layer aliases (#​30948)
• kit,nuxt,vite: directoryToURL to normalise paths (#​30986)
• nuxt: Allow forcing start/set in loading indicator (#​30989)
• nuxt: Allow specifying glob patterns for scanning pages/ (#​31090)
• nuxt: Add types for default NuxtLink slot (#​31104)
• nuxt: Delayed/lazy hydration support (#​26468)
• vite: Add vite's modulepreload polyfill (#​31164)
• nuxt: Show source file when warning about undefined useAsyncData (#​31144)
• kit,nuxt: Augment nitro types with addTypeTemplate (#​31079)
• kit,nuxt: Resolve template imports from originating module (#​31175)
• nuxt: Use oxc-parser instead of esbuild + acorn (#​30066)
• nuxt: Upgrade to unhead v2 (#​31169)
• nuxt: Align nuxt error handling with nitro (#​31230)

🔥 Performance

• nuxt: Remove duplicated nitro alias resolution (#​31088)
• kit: Try non-subpath routes first to resolve nuxt modules (#​31037)
• nuxt: Migrate to use exsolve for module resolution (#​31124)
• kit: Skip extra module resolution step in loadNuxt (#​31176)

🩹 Fixes

• nuxt: Ensure <NuxtLayout> fallback prop is typed (#​30832)
• nuxt: Assign slot to be rendered for client components (#​30768)
• nuxt,vite: Do not override vite import conditions (#​30887)
• nuxt: Prevent keepalive cache reset (#​30807)
• nuxt: Remove div wrapper in client-only pages (#​30425)
• schema: Update type import to nitropack (aba75bd5a)
• vite: Use resolveId from vite-node to resolve deps (#​30922)
• schema: Normalise additional experimental options (63e0c342c)
• nuxt: Delete existing properties in app config HMR (#​30918)
• schema: Return null from resolve functions (d68e8ce57)
• schema: Check if app.head.meta values are undefined (#​30959)
• nuxt: Make shared/ directories available within layers (#​30843)
• kit: Ensure nuxt is loaded from cwd rather than parent dir (#​30910)
• ui-templates: Remove extra <pre> when rendering dev errors (9aab69ec4)
• nuxt: Use tsx loader for jsx blocks as well (#​31014)
• Remove unimplemented page:transition:start type (#​31040)
• kit: Expose module dependency errors (#​31035)
• nuxt: Deprioritise layer css imports (#​31020)
• nuxt: Ensure provide / inject work in setup of defineNuxtComponent (#​30982)
• nuxt: Decode URI components in cache driver methods (#​30973)
• nuxt: Use _ for NuxtIsland name on server pages (#​31072)
• nuxt: Use ohash to calculate legacy async data key without hash (#​31087)
• nuxt,schema: Resolve shared dir from config (#​31091)
• kit,schema: Set esbuild target for experimental decorators (#​31089)
• nuxt: Set nuxt.options.pages to detected configuration (#​31101)
• nuxt: Warn when definePageMeta does not receive an object (#​31156)
• nuxt: Fix nitro import statements for v2 (151cf7d49)
• nuxt: Update path to no-ssr middleware handler (a99c59fbd)
• nuxt: Align type of custom navigate with vue-router (7a1934509)
• nuxt: Show error page on island page error (#​31081)
• nuxt: Do not render payloads if disabled, and correct regexp (#​31167)
• nuxt: Add backwards-compatible serialisation for nuxt.options.pages (fa480e0a0)
• ui-templates: Escape inline scripts correctly in ui templates (39c2b0a2c)
• nuxt: Add back fallback nuxtlink type signature (a8856de59)
• kit: Provide default extensions in resolveModule (6fb5c9c15)
• nuxt: Provide default extensions in resolveTypePath (a0f9ddfe2)
• nuxt: Strip query before generating payload url (34ddc2d2f)
• schema: Resolve workspaceDir to closest git config (7a2fbce01)
• kit: Include declaration files when resolving compilerOptions.paths (835e89404)
• nuxt: Consolidate head component context (#​31209)
• nuxt: Resolve shared externals to absolute paths (#​31227)
• nuxt: Skip deep merge in dev mode for prototype keys (#​31205)
• schema: Use RawVueCompilerOptions for unresolved tsconfig (#​31202)
• nuxt: Ensure externals are resolved first (#​31235)
• nuxt: Ensu